TypeScript 精确类型：用于健壮代码的严格对象形状匹配

TypeScript，作为 JavaScript 的一个超集，为动态的 Web 开发世界带来了静态类型。虽然 TypeScript 在类型安全和代码可维护性方面提供了显著优势，但其结构化类型系统有时也可能导致意外行为。这正是“精确类型”概念发挥作用的地方。尽管 TypeScript 没有一个明确名为“精确类型”的内置功能，但我们可以通过结合 TypeScript 的特性和技巧来实现类似的行为。这篇博客文章将深入探讨如何在 TypeScript 中强制执行更严格的对象形状匹配，以提高代码的健壮性并防止常见错误。

理解 TypeScript 的结构化类型

TypeScript 采用结构化类型（也称为鸭子类型），这意味着类型的兼容性是由类型的成员决定的，而不是由其声明的名称决定的。如果一个对象拥有某个类型所需的所有属性，那么它就被认为与该类型兼容，无论它是否拥有额外的属性。

例如：

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}

printPoint(myPoint); // 这段代码可以正常工作，尽管 myPoint 含有 'z' 属性

在这种情况下，TypeScript 允许将 `myPoint` 传递给 `printPoint`，因为它包含了必需的 `x` 和 `y` 属性，即使它有一个额外的 `z` 属性。虽然这种灵活性很方便，但如果你无意中传递了具有意外属性的对象，也可能导致潜在的 bug。

多余属性带来的问题

结构化类型的宽容性有时会掩盖错误。考虑一个期望接收配置对象的函数：

interface Config {
  apiUrl: string;
  timeout: number;
}

function setup(config: Config) {
  console.log(`API URL: ${config.apiUrl}`);
  console.log(`Timeout: ${config.timeout}`);
}

const myConfig = { apiUrl: "https://api.example.com", timeout: 5000, typo: true };

setup(myConfig); // TypeScript 在这里不会报错！

console.log(myConfig.typo); // 打印出 true。这个多余的属性悄无声息地存在着

在这个例子中，`myConfig` 有一个额外的属性 `typo`。TypeScript 没有报错，因为 `myConfig` 仍然满足 `Config` 接口。然而，这个拼写错误从未被发现，如果这个拼写错误本应是 `typoo`，应用程序的行为可能就不符合预期。在调试复杂的应用程序时，这些看似微不足道的问题可能会演变成重大的麻烦。在处理嵌套对象时，一个缺失或拼写错误的属性尤其难以检测。

在 TypeScript 中强制执行精确类型的方法

虽然 TypeScript 中没有直接可用的“精确类型”，但有几种技术可以实现类似的结果并强制执行更严格的对象形状匹配：

1. 使用 `Omit` 和类型断言

`Omit` 工具类型允许你通过从现有类型中排除某些属性来创建一个新类型。结合类型断言，这可以帮助防止多余的属性。

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

// 创建一个只包含 Point 属性的类型
const exactPoint: Point = myPoint as Omit & Point;

// 错误：类型 '{ x: number; y: number; z: number; }' 不能赋值给类型 'Point'。
// 对象字面量只能指定已知的属性，但 'z' 在类型 'Point' 中不存在。

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}


// 修正
const myPointCorrect = { x: 10, y: 20 };
const exactPointCorrect: Point = myPointCorrect as Omit & Point;
printPoint(exactPointCorrect);

如果 `myPoint` 拥有 `Point` 接口中未定义的属性，这种方法会抛出错误。

解释：`Omit` 创建了一个从 `myPoint` 类型中省略所有存在于 `Point` 中的键的类型。然后 `& Point` 将这个类型与 `Point` 类型进行交叉，本质上要求对象符合 `Point` 类型。通过将对象断言为这个组合类型，编译器会检查多余的属性，如果发现任何多余属性，就会抛出错误。这迫使我们在初次定义对象时就声明正确的形状。

2. 使用函数创建对象

你可以创建一个只接受接口中定义的属性的工厂函数。这种方法在对象创建时提供了强类型检查。

interface Config {
  apiUrl: string;
  timeout: number;
}

function createConfig(config: Config): Config {
  return {
    apiUrl: config.apiUrl,
    timeout: config.timeout,
  };
}

const myConfig = createConfig({ apiUrl: "https://api.example.com", timeout: 5000 });

// 这段代码将无法编译：
//const myConfigError = createConfig({ apiUrl: "https://api.example.com", timeout: 5000, typo: true });
// 类型 '{ apiUrl: string; timeout: number; typo: true; }' 的参数不能赋值给类型为 'Config' 的参数。
// 对象字面量只能指定已知的属性，但 'typo' 在类型 'Config' 中不存在。

通过返回一个仅由 `Config` 接口中定义的属性构成的对象，你可以确保没有多余的属性混入。这使得创建配置更加安全。

3. 使用类型守卫

类型守卫是一种函数，它可以在特定作用域内缩小变量的类型范围。虽然它们不直接防止多余属性，但可以帮助你显式地检查这些属性并采取适当的行动。

interface User {
  id: number;
  name: string;
}

function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'number' &&
    'name' in obj && typeof obj.name === 'string' &&
    Object.keys(obj).length === 2 // 检查键的数量。注意：这种方式很脆弱，依赖于 User 的确切键数。
  );
}

const potentialUser1 = { id: 123, name: "Alice" };
const potentialUser2 = { id: 456, name: "Bob", extra: true };

if (isUser(potentialUser1)) {
  console.log("Valid User:", potentialUser1.name);
} else {
  console.log("Invalid User");
}

if (isUser(potentialUser2)) {
  console.log("Valid User:", potentialUser2.name); // 不会执行到这里
} else {
  console.log("Invalid User");
}

在这个例子中，`isUser` 类型守卫不仅检查所需属性的存在性，还检查它们的类型以及属性的*确切*数量。这种方法更加明确，并允许你优雅地处理无效对象。然而，检查属性数量的方法是脆弱的。每当 `User` 增加或减少属性时，这个检查就必须更新。

4. 利用 `Readonly` 和 `as const`

虽然 `Readonly` 可以防止修改现有属性，`as const` 可以创建一个只读元组或对象，其中所有属性都是深度只读且具有字面量类型，但它们与其他方法结合使用时，可以创建更严格的定义和类型检查。不过，它们本身都不能防止多余属性。

interface Options {
  width: number;
  height: number;
}

// 创建 Readonly 类型
type ReadonlyOptions = Readonly;

const options: ReadonlyOptions = { width: 100, height: 200 };

//options.width = 300; // 错误：无法赋值给 'width'，因为它是只读属性。

// 使用 as const
const config = { api_url: "https://example.com", timeout: 3000 } as const;

//config.timeout = 5000; // 错误：无法赋值给 'timeout'，因为它是只读属性。

// 然而，多余的属性仍然被允许：
const invalidOptions: ReadonlyOptions = { width: 100, height: 200, depth: 300 }; // 没有错误。仍然允许多余的属性。


interface StrictOptions {
  readonly width: number;
  readonly height: number;
}

// 这时将会报错：
//const invalidStrictOptions: StrictOptions = { width: 100, height: 200, depth: 300 };
// 类型 '{ width: number; height: number; depth: number; }' 不能赋值给类型 'StrictOptions'。
//   对象字面量只能指定已知的属性，但 'depth' 在类型 'StrictOptions' 中不存在。

这提高了不可变性，但只防止了修改，而没有防止多余属性的存在。与 `Omit` 或函数方法结合使用时，它会变得更有效。

5. 使用库（例如 Zod, io-ts）

像 Zod 和 io-ts 这样的库提供了强大的运行时类型验证和模式定义功能。这些库允许你定义精确描述数据预期形状的模式，包括防止多余属性。虽然它们增加了一个运行时依赖，但它们提供了一个非常健壮和灵活的解决方案。

Zod 示例：

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

type User = z.infer;

const validUser = { id: 1, name: "John" };
const invalidUser = { id: 2, name: "Jane", extra: true };

const parsedValidUser = UserSchema.parse(validUser);
console.log("Parsed Valid User:", parsedValidUser);

try {
  const parsedInvalidUser = UserSchema.parse(invalidUser);
  console.log("Parsed Invalid User:", parsedInvalidUser); // 这行代码不会被执行到
} catch (error) {
  console.error("Validation Error:", error.errors);
}

如果输入不符合模式，Zod 的 `parse` 方法会抛出错误，从而有效地防止多余属性。这提供了运行时验证，并能从模式中生成 TypeScript 类型，确保了类型定义和运行时验证逻辑之间的一致性。

强制执行精确类型的最佳实践

在 TypeScript 中强制执行更严格的对象形状匹配时，请考虑以下最佳实践：

• 选择正确的技术：最佳方法取决于你的具体需求和项目要求。对于简单情况，使用 `Omit` 的类型断言或工厂函数可能就足够了。对于更复杂的场景或需要运行时验证的情况，可以考虑使用像 Zod 或 io-ts 这样的库。
• 保持一致性：在整个代码库中一致地应用你选择的方法，以保持统一的类型安全级别。
• 为你的类型编写文档：清晰地记录你的接口和类型，以便向其他开发者传达你数据的预期形状。
• 测试你的代码：编写单元测试来验证你的类型约束是否按预期工作，并确保你的代码能优雅地处理无效数据。
• 考虑权衡：强制执行更严格的对象形状匹配可以使你的代码更健壮，但也会增加开发时间。权衡利弊，选择对你的项目最有意义的方法。
• 逐步采用：如果你正在处理一个大型的现有代码库，考虑逐步采用这些技术，从应用程序最关键的部分开始。
• 定义对象形状时优先使用接口而非类型别名：通常首选接口，因为它们支持声明合并，这在跨不同文件扩展类型时很有用。

真实世界示例

让我们看一些精确类型能带来好处的真实世界场景：

• API 请求负载：在向 API 发送数据时，确保负载符合预期的模式至关重要。强制执行精确类型可以防止因发送意外属性而导致的错误。例如，许多支付处理 API 对意外数据极其敏感。
• 配置文件：配置文件通常包含大量属性，拼写错误很常见。使用精确类型可以帮助及早发现这些错误。如果你在云部署中设置服务器位置，位置设置中的一个拼写错误（例如 eu-west-1 vs. eu-wet-1）如果没有预先捕获，将变得极其难以调试。
• 数据转换管道：当将数据从一种格式转换为另一种格式时，确保输出数据符合预期的模式很重要。
• 消息队列：当通过消息队列发送消息时，确保消息负载有效并包含正确的属性很重要。

示例：国际化 (i18n) 配置

想象一下管理一个多语言应用程序的翻译。你可能会有这样一个配置对象：

interface Translation {
  greeting: string;
  farewell: string;
}

interface I18nConfig {
  locale: string;
  translations: Translation;
}

const englishConfig: I18nConfig = {
  locale: "en-US",
  translations: {
    greeting: "Hello",
    farewell: "Goodbye"
  }
};


// 这会是个问题，因为存在一个多余的属性，悄无声息地引入了一个 bug。
const spanishConfig: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós",
    typo: "unintentional translation"
  }
};

// 解决方案：使用 Omit
const spanishConfigCorrect: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós"
  } as Omit & Translation
};

如果没有精确类型，翻译键中的拼写错误（比如添加了一个 `typo` 字段）可能会被忽略，导致用户界面中出现翻译缺失。通过强制执行更严格的对象形状匹配，你可以在开发期间捕获这些错误，防止它们进入生产环境。

结论

虽然 TypeScript 没有内置的“精确类型”，但你可以通过结合使用 TypeScript 的特性和技术来实现类似的结果，例如使用 `Omit` 的类型断言、工厂函数、类型守卫、`Readonly`、`as const` 以及像 Zod 和 io-ts 这样的外部库。通过强制执行更严格的对象形状匹配，你可以提高代码的健壮性，防止常见错误，并使你的应用程序更加可靠。请记住选择最适合你需求的方法，并在整个代码库中保持一致的应用。通过仔细考虑这些方法，你可以更好地控制应用程序的类型，并提高长期的可维护性。